Agent开发完全实战指南(十一)Agent Skills
你给 Agent 攒了一身本事:一套 commit message 规范、一份周报模板、一段"处理 PDF 要先转版面再切块"的 SOP。问题是这些东西散落得到处都是——有的写在 CLAUDE.md 里,有的硬编码在 Go 代码里,有的干脆只在你脑子里。换个项目就得重抄一遍,工具一多上下文就爆,模型还经常"忘了"该按你的规矩来。
2025 年 10 月,Anthropic 推出 Agent Skills;同年 12 月它被开放成标准,OpenAI、Google、GitHub Copilot、Cursor 几周内相继跟进。这不是又一个框架,而是一个朴素到极致的约定:
一个 Skill,就是一个装着
SKILL.md的文件夹。 把"怎么把这件事做对"打包成文件,让 Agent 需要时自己去读。
这一篇我们讲透 Skill 的本质和它最核心的设计——渐进式披露(progressive disclosure),然后用 Go 从零手搓一个 Skill 加载器,接到第 02 篇的 Agent 循环上,亲眼看它三级加载。
一、先说人话:Skill 到底是什么
一个 Skill 就是一个文件夹,长这样:
commit-message/
├── SKILL.md # 必需:元数据(name + description)+ 操作说明
├── references/ # 可选:按需加载的深度资料
│ └── EXAMPLES.md
├── scripts/ # 可选:可执行脚本
└── assets/ # 可选:模板、样例文件
核心只有 SKILL.md,头部是 YAML frontmatter(name 和 description),下面是给模型看的操作说明。它装的不是"能力"本身,而是"程序性知识"——把一件事该怎么一步步做对,写成模型能读的说明书。
它和你已经会的两样东西是什么关系?一张表说清:
| 抽象 | 是什么 | 一句话 |
|---|---|---|
| Tool(工具) | 一个有类型输入输出的函数 | 做一个确定动作(读文件、发 HTTP) |
| MCP | 连接外部系统的开放协议 | 提供访问(AI 世界的 USB-C 接口) |
| Skill | 装着 SKILL.md 的文件夹 | 教模型把活儿做对的完整流程(步骤、格式、验收标准) |
关键洞察:Tool 是"能做什么",MCP 是"能连到什么",Skill 是"该怎么做"。三者不是竞争,是三层。 一个 Slack 客服 Agent 往往三样都要:MCP 连上工单系统,Tool 执行创建工单,Skill 规定"什么样的问题该建单、回复用什么语气"。
二、核心机制:渐进式披露
Skill 真正的精髓不在文件夹,而在它怎么被加载。
先想清楚要解决的问题:上下文窗口是 Agent 的认知空间,塞满就退化(这就是第 04、06 篇反复出现的 lost-in-the-middle)。如果你有 100 个 Skill,把 100 份正文全塞进去,Agent 还没干活上下文就废了。
渐进式披露的答案是分三级、按需加载:
flowchart TD
A["启动:扫描所有 skill
只读 name + description"] --> B{"来了个任务
有 skill 相关吗?"}
B -->|"没有"| Z["直接回答,一个字节正文都不加载"]
B -->|"有"| C["Activation:读那个 skill
的完整 SKILL.md 正文"]
C --> D{"正文让我读
references 里的文件吗?"}
D -->|"不需要"| E["按说明执行"]
D -->|"需要"| F["Execution:只读用得上的
那个引用文件"]
F --> E三级各花多少钱,Anthropic 官方 17 个 skill 的实测很能说明问题:
| 级别 | 加载什么 | 上下文成本 |
|---|---|---|
| Discovery(启动) | 每个 skill 的 name + description | 中位数约 80 token/skill(55–235) |
| Activation(命中) | 那一个 skill 的 SKILL.md 正文 | 几百到上千 token,只在相关时 |
| Execution(执行) | 用得上的 references 文件 / 脚本输出 | 按需,其余永远躺在磁盘上 不花钱 |
关键洞察:这就是 Skill 能"装一屋子却不撑爆上下文"的原因——启动只装一份目录,正文和资料都等模型真正需要时才逐级取用。 打个比方:一个同事记得整本手册的目录,但没读任何一章;要用哪章时才翻到哪章。
三、Skill vs Tool vs MCP:到底该用哪个
Anthropic 官方用了个厨房比喻,很好记:MCP 给你一间专业厨房(接上食材和设备),Tool 是"切"这个动作,Skill 是这道菜的菜谱——告诉你在你这家店里该怎么做。
落到选型上:
| 你的问题是 | 用 |
|---|---|
| 要连一个外部系统(数据库 / GitHub / 内部 API),且跨会话、跨项目复用 | MCP |
| 要执行一个离散动作,一步就完 | Tool |
| 要让模型每次都用同样的高质量流程做一件需要判断的事 | Skill |
| 既要判断又要动作(绝大多数真实活儿) | Skill 引用 Tool:Skill 给流程,Tool 给执行 |
一个决定性的技术差异是上下文占用方式:Tool 的声明每条消息都在上下文里(除非用动态工具搜索),而 Skill 靠渐进式披露,不相关时零占用。所以当你有大量领域知识要沉淀,又不想每次会话重讲一遍,Skill 是那个"装得多、平时不占地"的选择。
四、动手:用 Go 手搓一个渐进式 Skill 加载器
概念够了,动手。我们复用 第 02 篇 的 Agent 循环,把渐进式披露的三级做出来:Discovery 扫元数据注入系统提示,Activation / Execution 做成两个工具挂上去。完整代码在 code/11-skills/。
4.1 先看一个 Skill 长啥样
skills/commit-message/SKILL.md:
---
name: commit-message
description: 写规范的 Git commit message。当用户要提交代码、生成 commit 信息、整理本次改动说明时使用。
---
# 写一条规范的 Commit Message
按 Conventional Commits 规范产出,格式如下:
...
- 需要更多正反例时,读 `references/EXAMPLES.md`(只有需要时才读)。
注意最后那句——正文自己指路,把深度资料推迟到 Execution 级再加载。
4.2 第 1 级 Discovery:只读 frontmatter
启动时遍历 skills/,只解析 frontmatter,绝不读正文:
// 只解析 YAML frontmatter 的 name / description,正文一个字节都不读
func parseFrontmatter(path string) (name, desc string, ok bool) {
raw, err := os.ReadFile(path)
if err != nil {
return "", "", false
}
text := string(raw)
if !strings.HasPrefix(text, "---") {
return "", "", false
}
rest := text[3:]
end := strings.Index(rest, "\n---") // 第二道 --- 之前就是 frontmatter
if end < 0 {
return "", "", false
}
for _, line := range strings.Split(rest[:end], "\n") {
k, v, found := strings.Cut(line, ":")
if !found {
continue
}
switch strings.TrimSpace(k) {
case "name":
name = strings.TrimSpace(v)
case "description":
desc = strings.TrimSpace(v)
}
}
return name, desc, name != "" && desc != ""
}
把所有 name+description 拼成一份"目录",注入系统提示——这就是 Agent 启动时对 skill 的全部认知。
4.3 第 2、3 级:两个工具
Activation 和 Execution 各是一个工具,挂进第 02 篇那个 toolRegistry:
// Activation:读某个 skill 的完整正文
func loadSkill(args map[string]any) string {
s := skillIndex[args["name"].(string)]
body, _ := os.ReadFile(filepath.Join(s.Dir, "SKILL.md"))
return string(body)
}
// Execution:读 skill 目录下的引用文件——注意挡住路径穿越
func readReference(args map[string]any) string {
s := skillIndex[args["skill"].(string)]
base, _ := filepath.Abs(s.Dir)
target, _ := filepath.Abs(filepath.Join(s.Dir, args["path"].(string)))
if !strings.HasPrefix(target, base+string(os.PathSeparator)) {
return "错误:拒绝越界访问" // 挡掉 ../../etc/passwd
}
data, _ := os.ReadFile(target)
return string(data)
}
模型在系统提示里看到目录,判断相关就调 load_skill 读正文,正文让它读引用它才调 read_reference。三级披露,全在这个循环里自然发生。
4.4 跑起来
cd code/11-skills
go run .
你会先看到 Discovery 的账本,再看到模型逐级取用:
发现 2 个 skill;目录占 280 字节,全部正文占 1728 字节——启动只装目录,省下 1448 字节的上下文。
可用 skills(注入系统提示的目录):
- commit-message: 写规范的 Git commit message。当用户要提交代码...
- weekly-report: 把零散的工作记录整理成结构化周报...
用户:帮我根据这次改动写一条 commit message:把 Qdrant 的 upsert 从 POST 改成了 PUT,修好了写入失败
[调用] load_skill({"name":"commit-message"})
[结果] # 写一条规范的 Commit Message 按 Conventional Commits…
Agent:
fix(qdrant): upsert 改用 PUT 而非 POST
POST /collections/{}/points 会命中「按 ids 删除」的处理器,导致写入失败。
看那行"省下 1448 字节"——skill 只有两个就省了 84%,真实场景几十个 skill 时,这就是"能不能装得下"的分水岭。 模型没有被灌一堆无关正文,而是自己判断、自己去读那一个相关的。
五、写好一个 Skill 的最佳实践
手搓完你就懂了,写 Skill 的功夫全在几个地方:
- description 是命中率的唯一线索:Discovery 阶段模型只能看到它。必须同时写清"做什么 + 什么时候用",别只写"处理 PDF",要写"当用户要填 PDF 表单、提取 PDF 字段时使用"。官方限制 ≤1024 字符。
- name 有格式约束:≤64 字符,只能小写字母、数字、连字符,不能用
anthropic/claude这类保留词。 - 正文精简,深度拆到 references:SKILL.md 正文是 Activation 级成本,越短越好;长清单、正反例、详细规格全丢进
references/,正文里指路让模型按需读。 - 脚本只回输出:
scripts/里的代码通过 bash 跑,只有执行结果进上下文,源码不进——这是省 token 的又一层。 - 一个 Skill 只干一件事:粒度太粗,description 就说不清、命中就不准。
一句话记住:把 SKILL.md 正文当成"电梯演讲",把 references 当成"附录",让模型像查手册一样按需翻。
六、安全:Skill 是会被执行的代码
别被"就是几个 markdown 文件"骗了。Skill 的正文是模型会照着做的指令,scripts/ 是会被执行的代码——它同时是一条供应链和一个注入面。 这正是第 10 篇讲的攻击面在 Skill 形态下的延续。
三个必须守住的点:
- 来源信任:装第三方 Skill 等于往你的 Agent 里注入指令 + 可执行脚本,和
npm install一个陌生包同级别的风险。只用可信来源,装前读一遍。 - 路径要收口:Skill 读文件的能力必须限制在自己目录内——这就是上面
readReference里那道HasPrefix检查,挡掉../../etc/passwd式的穿越。 - 高危动作留人工:Skill 引用的 Tool 一旦能写库、能退款、能调 API,就要按第 10 篇的做法加 human-in-the-loop,别让一段被投毒的 SKILL.md 直接触发不可逆操作。
七、决策指南与小结
什么时候该掏出 Skill?一张决策表收尾:
| 情况 | 怎么办 |
|---|---|
| 一句话就能说清、且每次都一样 | 直接写进 system prompt,别做 skill |
| 一段需要判断的多步流程,要反复复用 | 做成 Skill |
| 只是要一个确定动作 | 写个 Tool |
| 要接外部系统、跨项目共享 | 起个 MCP server |
| 既要流程判断又要执行动作 | Skill 引用 Tool(覆盖绝大多数真实活儿) |
这一篇的收获:
- Skill = 一个装着 SKILL.md 的文件夹,打包的是"怎么把事做对"的程序性知识。
- 它的灵魂是渐进式披露:Discovery 只装目录 → Activation 命中读正文 → Execution 按需取资料,装得多却不撑爆上下文。
- Skill / Tool / MCP 是三层不是三选一:怎么做 / 做什么 / 连什么,真实系统三样都要。
- 写好 Skill 的功夫在 description(命中线索)和正文精简(成本控制);用好 Skill 的前提是把它当会被执行的代码来防。
至此,从第 01 篇的"一次 API 调用"到这里的"把能力打包复用",你已经走完了 Agent 工程的主干。Skill 是这套主干上最新、也最能立刻上手的一块拼图——回到你自己的项目,挑一个你反复向模型交代的流程,把它写成第一个 SKILL.md 吧。
参考资料
| 资料 | 来源 |
|---|---|
| Anthropic:Agent Skills 官方文档 | docs.anthropic.com/en/docs/agents/skills |
| Anthropic:Equipping agents for the real world with Agent Skills | anthropic.com/engineering |
| 渐进式披露作为系统设计模式(含 token 实测) | newsletter.swirlai.com/p/agent-skills-progressive-disclosure |
| Skills vs MCP vs Tools:该用哪个 | towardsdatascience.com/what-is-agent-skills-beyond-claude |
| Agent Skills for LLMs:架构、获取与安全综述 | arxiv.org/abs/2602.12430 |
| Agent Skills 开放标准与生态 | agentskills.io |